Dashboard Redesign Analysis

# Dashboard Redesign Analysis

## Conclusion (TL;DR)

**Approach**: Insight-Centric Dashboard Redesign (Phased Implementation)

| Item                | Change                                                      |
| ------------------- | ----------------------------------------------------------- |
| **Summary Section** | My analyzed repos stats (total tests, active repos, attention needed) |
| **Attention Zone**  | Highlight repos requiring action (focused, new-commits, etc.) |
| **Repository List** | 2-axis filter (ownership + bookmark), remove community      |
| **Discovery FAB**   | Screen-fixed (`position: fixed`)                            |
| **Community Separation** | Move to `/explore` page **(Phase 1 first)**            |

**Implementation Order**: Explore separation → Dashboard redesign → Advanced features

---

## Navigation Architecture

### Decision: Header Tabs + Horizontal Filter Bar

| Element | Choice | Rationale |
|---------|--------|-----------|
| **Primary Nav** | Header tabs | Developer tool trend (Vercel, GitHub, Linear) |
| **Filters** | Horizontal filter bar | 4 filters = no sidebar needed |
| **Mobile** | Bottom Tab Bar + Bottom Sheet | Modern responsive pattern |

### Why NOT Sidebar?

| Criteria | SpecVital | Verdict |
|----------|-----------|---------|
| Filter count | 4 | Horizontal bar (threshold: 6-8) |
| Filter complexity | Simple dropdowns/toggles | Horizontal bar |
| Industry pattern | GitHub, Vercel, Linear | Horizontal bar |

**Sidebar is appropriate when**: 8+ filter categories, faceted navigation, saved filter presets, hierarchical categories

### Desktop Layout

```
+------------------------------------------------------------------+
| [Logo] SpecVital   [Dashboard] [Explore]   [Theme][Lang][Avatar] |
+------------------------------------------------------------------+
| [Search........] [Ownership ▼] [Sort ▼] [★ Starred]   24 repos  |
+------------------------------------------------------------------+
| Summary Section                                                   |
| Attention Zone                                                    |
| Repository Cards (full width)                                     |
+------------------------------------------------------------------+
```

### Mobile Layout

```
+---------------------------+
| [≡] SpecVital      [👤]  |
+---------------------------+
| [Search...] [Filter ▼]   |  ← Filter = Bottom Sheet
+---------------------------+
| Summary Cards             |
| Attention Zone            |
| Repository Cards          |
+---------------------------+
| [Dashboard] [Explore] [+] |  ← Bottom Tab Bar
+---------------------------+
```

### Responsive Breakpoints

| Breakpoint | Layout |
|------------|--------|
| Desktop (>1200px) | Header tabs + Horizontal filter bar |
| Tablet (768-1200px) | Header tabs + Collapsible filter |
| Mobile (<768px) | Hamburger + Bottom Tab Bar + Bottom Sheet |

---

## SpecVital Essence

> "Enter GitHub URL → Instantly see test inventory"

| Feature             | Description                                 |
| ------------------- | ------------------------------------------- |
| **Zero-Friction**   | No CI/CD setup required, results in 5 seconds |
| **Static Analysis** | Tree-sitter AST-based, no test execution    |
| **Test Inventory**  | Not Pass/Fail, but "what tests exist"       |

### What Static Analysis Can vs Cannot Do

| Possible (API exists)                 | Impossible (requires execution) |
| ------------------------------------- | ------------------------------- |
| Test count                            | Pass/Fail results               |
| `focused`/`skipped`/`todo` detection  | Coverage %                      |
| Test distribution by file             | Execution time                  |
| Analysis commit SHA                   | Success rate trends             |
| **New commits** (`new-commits` status)| -                               |

---

## Problem Definition

### Current Dashboard Issues

1. **Unclear value**: Just card listing, lacking insights from static analysis
2. **Discovery pushed down**: Hard to access Discovery section after Load More clicks
3. **Community mixed in**: Other users' analyses mixed into personal dashboard
4. **Missing filters**: No ownership (mine/org/others) filter

### Core Questions

- "Which of my repositories need attention now?"
- "Is there `.only()` causing CI to skip other tests?"
- "Any new commits since last analysis?"
- "I want to see only my organization repos"

---

## Scope

**Included**:

- `/explore` page separation (prerequisite)
- Add Summary stats section
- Attention Zone (repositories needing action)
- Repository List filter redesign (ownership + bookmark)
- Discovery FAB conversion
- Apply Infinite Scroll

**Excluded**:

- "Health score" (hard to define meaningfully with static analysis only)
- Trend charts (requires history data)

---

## Solution Details

### Dashboard Layout

```
+----------------------------------------------------------+
| SUMMARY SECTION                                          |
| +------------+ +------------+ +---------------------------+
| | TOTAL      | | ACTIVE     | | ⚠️ ATTENTION             |
| | TESTS      | | REPOS      | | 3 repos need action      |
| | 12,543     | | 24         | |                          |
+----------------------------------------------------------+
| ⚠️ ATTENTION ZONE (conditional)                View All > |
| +-------------------+ +-------------------+ +----------+  |
| | repo-1            | | repo-2            | | +1 more  |  |
| | .only() found!    | | New commits       | |          |  |
| | [View Details]    | | [Re-analyze]      | |          |  |
+----------------------------------------------------------+
| REPOSITORY LIST                                          |
| [Search_______________]                                  |
| [All ▼] [★ Starred] [Sort: Recent ▼]                    |
|    ↓                                                     |
| ┌──────────────┐                                         |
| │ All          │                                         |
| │ Mine         │ <- My personal repos                    |
| │ Organization │ <- My org repos                         |
| │ Others       │ <- Repos I analyzed but don't own       |
| └──────────────┘                                         |
| +--------+ +--------+ +--------+ +--------+               |
| | Card 1 | | Card 2 | | Card 3 | | Card 4 |               |
+----------------------------------------------------------+
| (Infinite Scroll)                                         |
|                                    +------------------+   |
|                                    | + Discover [12]  |   | <- FAB
+----------------------------------------------------------+
```

---

### Summary Section Details

**Data Scope**: My analyzed repositories only (not entire DB)

| Item         | Data Source       | Description              |
| ------------ | ----------------- | ------------------------ |
| Total Tests  | Aggregation       | Total tests in my repos  |
| Active Repos | Aggregation       | Number of analyzed repos |
| Attention    | Conditional filter| Repos needing attention  |

**Why "My Repositories" Scope?**

- Summary purpose: "Understand my portfolio status"
- Attention purpose: "Alert for repos I can take action on"
- Others' repo stats are not actionable

---

### Attention Zone Details

**Data Scope**: My analyzed repositories only

#### Attention Situations

| Situation          | Severity | Condition              | Action       |
| ------------------ | -------- | ---------------------- | ------------ |
| **focused tests**  | Critical | `focused > 0`          | View Details |
| **new-commits**    | Warning  | `status = new-commits` | Re-analyze   |
| **Old analysis**   | Warning  | >7 days since analysis | Re-analyze   |
| **skipped ratio**  | Info     | `skipped/total > 30%`  | View Details |

#### `.only()` (focused tests) Problem Explained

When using `.only()` in test frameworks:

```javascript
describe('User', () => {
  it.only('should login', () => { ... }); // Only this runs!
  it('should logout', () => { ... });     // skip
  it('should update', () => { ... });     // skip
});
```

**The Problem**:

1. Developer uses `.only()` for local debugging
2. Forgets to remove before commit
3. **CI runs only that test, all others skipped**
4. Tests "pass" but most don't actually run!

**SpecVital's Value**:

- Static analysis detects `.only()` (focused)
- Warn before CI execution
- Show as Critical in Attention Zone

---

### Repository List Redesign

#### Filter Structure: 2 Independent Axes

| Axis        | Options                            | Purpose                   |
| ----------- | ---------------------------------- | ------------------------- |
| **Ownership** | All / Mine / Organization / Others | Filter by repo owner    |
| **Bookmark**  | All / Starred Only                 | Quick access filter     |

Both filters work **independently** (AND condition)

#### Ownership Filter Details

| Option           | Description                          | Example            |
| ---------------- | ------------------------------------ | ------------------ |
| **All**          | All repos I analyzed                 | -                  |
| **Mine**         | Repos I own                          | `username/repo`    |
| **Organization** | Repos my org owns                    | `my-org/repo`      |
| **Others**       | Repos I analyzed but don't own       | Others' public repos |

#### Filter UI

```
[All ▼] [★ Starred] [Sort: Recent ▼]
   ↓
┌──────────────┐
│ All          │  <- default
│ Mine         │
│ Organization │
│ Others       │
└──────────────┘
```

- **Ownership**: Dropdown (4 options)
- **Starred**: Toggle button (independent on/off)
- **Sort**: Dropdown (Recent / Tests / Name)

#### Community Separation

**Problem**: `community` filter shows entire DB in personal dashboard

**Solution**: Move Community to `/explore` page

| Current                               | After Change                   |
| ------------------------------------- | ------------------------------ |
| `all \| mine \| starred \| community` | Ownership dropdown + Starred toggle |

---

### Discovery FAB

**Problem**: Bottom Discovery section pushed by Infinite Scroll

**Solution**: Convert to FAB (Floating Action Button)

```css
.discovery-fab {
  position: fixed;
  bottom: 24px;
  right: 24px;
}
```

- **Desktop**: Fixed bottom-right (margin: 24px)
- **Mobile**: Bottom-right, above navigation bar (consider safe area)
- Click opens existing Sheet/Modal for Discovery
- Badge shows unanalyzed repo count

---

### `/explore` Page (Community Separation)

#### Purpose

Browse public analysis results + get inspiration from other repositories

#### Layout

```
+----------------------------------------------------------+
| EXPLORE                                                   |
| "Browse test setups from other developers"                |
+----------------------------------------------------------+
| TRENDING (Weekly Popular)                                 |
| +--------+ +--------+ +--------+ +--------+               |
| | Card 1 | | Card 2 | | Card 3 | | Card 4 |  [View All >] |
+----------------------------------------------------------+
| RECENTLY ANALYZED                                         |
| [Search] [Language Filter] [Sort]                        |
| +--------+ +--------+ +--------+ +--------+               |
| (Infinite Scroll)                                         |
+----------------------------------------------------------+
```

#### Dashboard vs Explore Differences

| Element     | Personal Dashboard | Explore              |
| ----------- | ------------------ | -------------------- |
| Data scope  | My analyses        | All public analyses  |
| Summary     | My stats           | Platform stats (opt) |
| Attention   | My repo warnings   | None                 |
| Primary action | Re-analyze, manage | Analyze           |
| Default sort | Recent analysis   | Popular              |

#### Entry Points

1. **GNB**: Dashboard | Explore tabs
2. **Dashboard CTA**: "Browse other repositories" link

```
+----------------------------------------------------------+
| 🏠 SpecVital     [Dashboard] [Explore]     [Profile ▼]   |
+----------------------------------------------------------+
```

---

## Implementation

### Phase 1: Explore Separation (Prerequisite)

> **Purpose**: Secure alternative path before removing community filter

#### 1.1 Create `/explore` Page

- Reuse existing `community` filter API (`view=community`)
- Search/sort functionality
- Infinite Scroll

#### 1.2 Update GNB

- Add Dashboard | Explore tabs
- Highlight current page

#### 1.3 Remove community filter from Dashboard

- Delete `community` option
- Keep existing filters: `all | mine | starred`

#### Phase 1 Completion Criteria

- [ ] `/explore` page shows all public analyses
- [ ] GNB has Dashboard | Explore tabs
- [ ] Dashboard `community` filter removed
- [ ] Existing community users → naturally migrate to Explore

---

### Phase 2: Dashboard Redesign

#### 2.1 Add Summary Section

- Total repos, total tests
- Use existing API

#### 2.2 Add Attention Zone

- `focused > 0`: Critical badge
- `status = new-commits`: Warning badge
- Conditional display (only when matching repos exist)

#### 2.3 Convert to Discovery FAB

- `position: fixed` bottom-right
- Click opens existing Sheet
- Unanalyzed repo count badge

#### 2.4 Apply Infinite Scroll

- Load More → IntersectionObserver auto-loading
- Use existing `useLoadMore` hook

#### 2.5 Filter Redesign

- Ownership dropdown (All/Mine/Organization)
- Add Starred toggle
- Use existing API (`ownership` parameter)

#### Phase 2 Completion Criteria

- [ ] Summary stats displayed at page top
- [ ] Critical badge on repos with `focused > 0`
- [ ] "Re-analysis needed" on `new-commits` repos
- [ ] Discovery FAB fixed on screen (`position: fixed`)
- [ ] Infinite Scroll works (auto next page load)
- [ ] Ownership filter works (All/Mine/Organization)
- [ ] Starred toggle works

---

### Phase 3: Filter Extension + Advanced Features

#### 3.1 Backend: Add `others` filter

```yaml
# openapi.yaml modification
ownership:
  enum: [all, mine, organization, others] # add others
```

- `others`: Repos I analyzed but don't own

#### 3.2 Explore Enhancement

- Trending section (weekly popular)
- Language filter

#### 3.3 Future Features

- Test count change trends (requires history storage)
- Team/Organization dashboard
- Cross-repository comparison

---

## API Status and Changes

### Existing API Available

| Data              | API Field                                | Status    |
| ----------------- | ---------------------------------------- | --------- |
| commit SHA        | `commitSha`, `analyzedCommitSha`         | Exists    |
| new-commits status| `status`                                 | Exists    |
| focused test count| `testSummary.focused`                    | Exists    |
| skipped test count| `testSummary.skipped`                    | Exists    |
| ownership filter  | `ownership: all \| mine \| organization` | Exists    |
| community filter  | `view: community`                        | Exists    |

### Backend Changes Required (Phase 3)

| Change                   | Description                               | Priority  |
| ------------------------ | ----------------------------------------- | --------- |
| `ownership: others` add  | Filter for repos I analyzed but don't own | Phase 3   |
| Trending API             | Weekly popular repos list                 | Phase 3   |

---

## Technical Implementation Checklist

### Phase 1 (Explore Separation)

- [ ] Frontend: `/explore` page and route
- [ ] Frontend: `ExploreContent` component
- [ ] Frontend: GNB tab navigation add
- [ ] Frontend: Dashboard `community` filter remove

### Phase 2 (Dashboard Redesign)

- [ ] `SummarySection` component
- [ ] `AttentionZone` component
- [ ] `DiscoveryFab` component
- [ ] `OwnershipFilter` dropdown component
- [ ] `StarredToggle` component
- [ ] Infinite Scroll (sentinel + IntersectionObserver)
- [ ] Mobile responsive testing

### Phase 3 (Filter Extension)

- [ ] Backend: `ownership: others` filter add
- [ ] Backend: Trending API endpoint
- [ ] Frontend: Explore Trending section

---

## Needs Confirmation

1. **Attention Criteria**
   - Critical if `focused` >= 1?
   - Show `skipped` warning at what %? (Proposal: 30%)

2. **Old Analysis Criteria**
   - 7 days? 14 days?

---

## Insights Suitable for SpecVital

| Insight        | Data Source         | User Value                      |
| -------------- | ------------------- | ------------------------------- |
| Total tests    | Aggregation         | Portfolio status overview       |
| `focused` detect | `testSummary`     | CI skipping other tests warning!|
| `skipped` many | `testSummary`       | Technical debt awareness        |
| `new-commits`  | `status`            | Re-analysis needed              |
| Analysis time  | `analyzedCommitSha` | Data freshness check            |

**SpecVital ≠ SonarQube/Codecov**:

- No execution results → Cannot provide Pass/Fail, coverage
- Static analysis → Provides "test inventory" + "quality signals"


Item	Change
Summary Section	My analyzed repos stats (total tests, active repos, attention needed)
Attention Zone	Highlight repos requiring action (focused, new-commits, etc.)
Repository List	2-axis filter (ownership + bookmark), remove community
Discovery FAB	Screen-fixed (`position: fixed`)
Community Separation	Move to `/explore` page (Phase 1 first)

Element	Choice	Rationale
Primary Nav	Header tabs	Developer tool trend (Vercel, GitHub, Linear)
Filters	Horizontal filter bar	4 filters = no sidebar needed
Mobile	Bottom Tab Bar + Bottom Sheet	Modern responsive pattern

Criteria	SpecVital	Verdict
Filter count	4	Horizontal bar (threshold: 6-8)
Filter complexity	Simple dropdowns/toggles	Horizontal bar
Industry pattern	GitHub, Vercel, Linear	Horizontal bar

Breakpoint	Layout
Desktop (>1200px)	Header tabs + Horizontal filter bar
Tablet (768-1200px)	Header tabs + Collapsible filter
Mobile (<768px)	Hamburger + Bottom Tab Bar + Bottom Sheet

Feature	Description
Zero-Friction	No CI/CD setup required, results in 5 seconds
Static Analysis	Tree-sitter AST-based, no test execution
Test Inventory	Not Pass/Fail, but "what tests exist"

Possible (API exists)	Impossible (requires execution)
Test count	Pass/Fail results
`focused`/`skipped`/`todo` detection	Coverage %
Test distribution by file	Execution time
Analysis commit SHA	Success rate trends
New commits (`new-commits` status)	-

Item	Data Source	Description
Total Tests	Aggregation	Total tests in my repos
Active Repos	Aggregation	Number of analyzed repos
Attention	Conditional filter	Repos needing attention

Situation	Severity	Condition	Action
focused tests	Critical	`focused > 0`	View Details
new-commits	Warning	`status = new-commits`	Re-analyze
Old analysis	Warning	>7 days since analysis	Re-analyze
skipped ratio	Info	`skipped/total > 30%`	View Details

Axis	Options	Purpose
Ownership	All / Mine / Organization / Others	Filter by repo owner
Bookmark	All / Starred Only	Quick access filter

Option	Description	Example
All	All repos I analyzed	-
Mine	Repos I own	`username/repo`
Organization	Repos my org owns	`my-org/repo`
Others	Repos I analyzed but don't own	Others' public repos

Element	Personal Dashboard	Explore
Data scope	My analyses	All public analyses
Summary	My stats	Platform stats (opt)
Attention	My repo warnings	None
Primary action	Re-analyze, manage	Analyze
Default sort	Recent analysis	Popular

Data	API Field	Status
commit SHA	`commitSha`, `analyzedCommitSha`	Exists
new-commits status	`status`	Exists
focused test count	`testSummary.focused`	Exists
skipped test count	`testSummary.skipped`	Exists
ownership filter	`ownership: all \| mine \| organization`	Exists
community filter	`view: community`	Exists

Change	Description	Priority
`ownership: others` add	Filter for repos I analyzed but don't own	Phase 3
Trending API	Weekly popular repos list	Phase 3

Insight	Data Source	User Value
Total tests	Aggregation	Portfolio status overview
`focused` detect	`testSummary`	CI skipping other tests warning!
`skipped` many	`testSummary`	Technical debt awareness
`new-commits`	`status`	Re-analysis needed
Analysis time	`analyzedCommitSha`	Data freshness check

Uh oh!

Dashboard Redesign Analysis #148

Description

Dashboard Redesign Analysis

Conclusion (TL;DR)

Navigation Architecture

Decision: Header Tabs + Horizontal Filter Bar

Why NOT Sidebar?

Desktop Layout

Mobile Layout

Responsive Breakpoints

SpecVital Essence

What Static Analysis Can vs Cannot Do

Problem Definition

Current Dashboard Issues

Core Questions

Scope

Solution Details

Dashboard Layout

Summary Section Details

Attention Zone Details

Attention Situations

.only() (focused tests) Problem Explained

Repository List Redesign

Filter Structure: 2 Independent Axes

Ownership Filter Details

Filter UI

Community Separation

Discovery FAB

/explore Page (Community Separation)

Purpose

Layout

Dashboard vs Explore Differences

Entry Points

Implementation

Phase 1: Explore Separation (Prerequisite)

1.1 Create /explore Page

1.2 Update GNB

1.3 Remove community filter from Dashboard

Phase 1 Completion Criteria

Phase 2: Dashboard Redesign

2.1 Add Summary Section

2.2 Add Attention Zone

2.3 Convert to Discovery FAB

2.4 Apply Infinite Scroll

2.5 Filter Redesign

Phase 2 Completion Criteria

Phase 3: Filter Extension + Advanced Features

3.1 Backend: Add others filter

3.2 Explore Enhancement

3.3 Future Features

API Status and Changes

Existing API Available

Backend Changes Required (Phase 3)

Technical Implementation Checklist

Phase 1 (Explore Separation)

Phase 2 (Dashboard Redesign)

Phase 3 (Filter Extension)

Needs Confirmation

Insights Suitable for SpecVital

Sub-issues

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`.only()` (focused tests) Problem Explained

`/explore` Page (Community Separation)

1.1 Create `/explore` Page

3.1 Backend: Add `others` filter