syntaxis/docs/core/features.md

# Syntaxis - Features Guide

Comprehensive feature comparison and documentation for the **Terminal UI (TUI)** and **Web Dashboard** interfaces.

---

## 📊 Feature Parity Matrix

### Project Management

| Feature | TUI | Dashboard | Notes |
|---------|-----|-----------|-------|
| View Projects List | ✅ | ✅ | Table/grid display of all projects |
| View Project Details | ✅ | ✅ | Detailed information per project |
| Create Projects | ✅ | ✅ | Form-based project creation |
| Delete Projects | ❌ | ✅ | Future TUI enhancement |
| Search Projects | ❌ | ✅ | Filter by name/description |
| View Security Assessments | ✅ | ✅ | Security profile & risk levels |
| Project Phases | ✅ | ✅ | Track current phase |

### Task Management

| Feature | TUI | Dashboard | Notes |
|---------|-----|-----------|-------|
| View Task List | ✅ | ✅ | All tasks for a project |
| Create Tasks | ✅ | ✅ | Add new tasks/checklists |
| Complete/Uncomplete Tasks | ✅ | ✅ | Toggle completion status |
| Task Priority Levels | ✅ | ✅ | Critical, High, Medium, Low |
| Task Type Classifications | ✅ | ✅ | Feature, BugFix, Documentation, Testing, Deployment, Maintenance |
| View Task Details | ✅ | ✅ | ID, description, priority, type, status |

### Task Sorting

| Sort Option | TUI | Dashboard | Details |
|-------------|-----|-----------|---------|
| Newest First | ✅ | ✅ | Sort by creation date (descending) |
| Oldest First | ✅ | ✅ | Sort by creation date (ascending) |
| Highest Priority | ✅ | ✅ | Critical → High → Medium → Low |
| Lowest Priority | ✅ | ✅ | Low → Medium → High → Critical |
| Completed First | ✅ | ✅ | Completed tasks before pending |
| Pending First | ✅ | ✅ | Pending tasks before completed |
| **Total Sort Options** | **6** | **6** | **Feature Parity Achieved ✅** |

### Task Filtering

| Feature | TUI | Dashboard | Details |
|---------|-----|-----------|---------|
| Show All Tasks | ✅ | ✅ | Display entire task list |
| Show Pending Only | ✅ | ✅ | Filter to incomplete tasks |
| Show Completed Only | ✅ | ✅ | Filter to completed tasks |
| Search by Description | ✅ | ✅ | Real-time text search |
| Filter by Priority | ❌ | ✅ | Future TUI enhancement |

### Task Statistics

| Metric | TUI | Dashboard | Details |
|--------|-----|-----------|---------|
| Total Tasks Count | ✅ | ✅ | Complete task count |
| Completed Count | ✅ | ✅ | Number of completed tasks |
| Pending Count | ✅ | ✅ | Number of incomplete tasks |
| Completion Percentage | ✅ | ✅ | (Completed / Total) × 100 |
| Progress Bar | ✅ | ✅ | Visual progress visualization |
| Per-Priority Statistics | ❌ | ✅ | Breakdown by priority level |
| Per-Type Statistics | ❌ | ✅ | Breakdown by task type |

### User Interface

| Feature | TUI | Dashboard | Details |
|---------|-----|-----------|---------|
| Keyboard Navigation | ✅ | ⚠️ | TUI has vim-style (hjkl) keys |
| Mouse Support | ❌ | ✅ | Dashboard has full mouse support |
| Responsive Design | ✅ | ✅ | Adapts to screen/window size |
| Color Themes | ❌ | ✅ | Future enhancement for TUI |
| Dark Mode | ❌ | ✅ | Supported in Dashboard |
| Real-time Updates | ✅ | ✅ | Live data synchronization |

---

## 🎯 Task Priority Levels

Both TUI and Dashboard support identical priority classifications:

```
Critical (🔴) - Highest priority, needs immediate attention
High (🟠)     - Important, should be completed soon
Medium (🟡)   - Standard priority (default)
Low (🟢)      - Can be deferred
```

### Priority Sorting Behavior

- **Highest Priority Sort**: Critical → High → Medium → Low
- **Lowest Priority Sort**: Low → Medium → High → Critical
- **Default Priority**: Medium (applied to tasks without explicit priority)

---

## 🏷️ Task Type Classifications

Both TUI and Dashboard recognize six task type categories:

| Type | Icon | Purpose | Use Case |
|------|------|---------|----------|
| Feature | ⭐ | New feature implementation | Building new capabilities |
| BugFix | 🐛 | Bug fixes and patches | Fixing issues and regressions |
| Documentation | 📚 | Documentation and guides | Writing docs and guides |
| Testing | ✔ | Testing and QA tasks | Quality assurance work |
| Deployment | 🚀 | Deployment and release | Release management |
| Maintenance | 🔧 | Maintenance and updates | Ongoing maintenance work |

### Default Task Type

When a task doesn't specify a type, it defaults to **Feature**.

---

## 📈 Statistics Calculation

### Real-time Metrics

Both TUI and Dashboard continuously calculate:

1. **Total Tasks**: Sum of all tasks in a project
   ```
   Total = Count(all tasks)
   ```

2. **Completed Count**: Tasks marked as done
   ```
   Completed = Count(tasks where completed == true)
   ```

3. **Pending Count**: Tasks not yet completed
   ```
   Pending = Total - Completed
   ```

4. **Completion Percentage**: Project progress indicator
   ```
   Percentage = (Completed / Total) × 100
   ```

5. **Progress Bar**: Visual representation
   - Filled: █ (completed)
   - Empty: ░ (pending)

### Example Calculation

For a project with 10 tasks (7 completed, 3 pending):
```
Total:           10
Completed:       7
Pending:         3
Completion %:    70.0%
Progress Bar:    [███████░░]
```

---

## 🎨 Display Examples

### Terminal UI (TUI) - Task Statistics Screen

```
┌─ Statistics ──────────────────────────────────────────────┐
│ Total: 10 | Completed: 7 ✓ | Pending: 3 ⏳ | Progress: 70.0%
│
│ [███████░░]                                               │
└──────────────────────────────────────────────────────────┘

┌─ Tasks (10) [Filtered] ───────────────────┬─ Details ─────────┐
│ [✓] Implement authentication              │ ID: task_001      │
│ [ ] Add caching layer                     │ Priority: High    │
│ [✓] Write documentation                   │ Type: Feature     │
│ [ ] Setup CI/CD pipeline                  │                   │
│ [✓] Deploy to staging                     │ Status: Completed │
│ ...                                        │ Created: 2025-... │
└────────────────────────────────────────────┴───────────────────┘

Help: q/Esc: Quit | ↑↓: Navigate | Space: Toggle | n: New | /: Filter
```

### Web Dashboard - Task Statistics Display

```
┌─────────────────────────────────────────────────────────┐
│ Statistics                                              │
│─────────────────────────────────────────────────────────│
│ ┌──────────┐  ┌──────────┐  ┌──────────────┐           │
│ │ Total    │  │Completed │  │ Completion % │           │
│ │    10    │  │    7     │  │    70.0%     │           │
│ └──────────┘  └──────────┘  └──────────────┘           │
│                                                         │
│ [███████░░]                                            │
└─────────────────────────────────────────────────────────┘
```

---

## ⌨️ Terminal UI (TUI) Key Bindings

### General Navigation
- **q** or **Esc**: Quit application
- **Tab**: Switch between main screens

### Projects Screen
- **↑/k** or **↓/j**: Navigate projects
- **Enter**: View project details
- **c**: Create new project
- **s**: View security assessments

### Tasks Screen
- **↑/k** or **↓/j**: Navigate task list
- **Space**: Toggle task completion
- **n**: Create new task
- **/**: Open sort/filter menu
- **f**: Toggle completion filter
- **c**: Clear all filters
- **←/h** or **→/l**: Navigate sort options
- **Enter**: Apply selected sort
- **b**: Back to project details

### Edit Screens
- **b**: Cancel and go back

---

## 🔄 Implementation Details

### Data Models

Both TUI and Dashboard use identical data structures:

```rust
struct ChecklistItemDto {
    id: String,
    task_id: String,
    description: String,
    completed: bool,
    completed_at: Option<String>,
    created_at: String,
    priority: TaskPriority,        // Added in Phase 12
    task_type: TaskType,           // Added in Phase 12
}

enum TaskPriority {
    Critical,
    High,
    Medium,
    Low,
}

enum TaskType {
    Feature,
    BugFix,
    Documentation,
    Testing,
    Deployment,
    Maintenance,
}
```

### Backward Compatibility

Both applications use `#[serde(default)]` attributes on new fields, ensuring compatibility with older API versions that don't return priority/type information.

### Sorting Implementation

Type-safe sorting using Rust enums:

```rust
pub(crate) enum TaskSortOption {
    CreatedNewest,
    CreatedOldest,
    PriorityHighest,
    PriorityLowest,
    CompletedFirst,
    PendingFirst,
}
```

---

## 📋 Comparison Summary

### When to Use TUI

✅ **Best for:**
- Command-line workflows
- Remote SSH sessions (no GUI needed)
- Power users comfortable with keyboard navigation
- Minimal resource usage
- Quick task management without browser overhead

### When to Use Dashboard

✅ **Best for:**
- Team collaboration (shared dashboard view)
- Visual project overview
- Mouse-based navigation preference
- Complex filtering and analysis
- Advanced reporting (per-priority/type statistics)
- Mobile/tablet access (responsive web design)

### Feature Parity (Phase 12)

**TUI Capabilities:**
- 6 sort options ✅
- Task statistics with progress bar ✅
- Priority and type support ✅
- Real-time filtering ✅
- Vim-style navigation ✅

**Dashboard Capabilities:**
- 6 sort options ✅
- Task statistics with breakdown ✅
- Priority and type support ✅
- Advanced filtering (by priority/type) ✅
- Mouse and keyboard support ✅
- Mobile responsive design ✅

---

## 🚀 Roadmap

### Short Term (Next Sprint)
- [ ] Display priority/type badges in TUI task list
- [ ] Filter by priority in TUI
- [ ] Dashboard export to CSV/JSON
- [ ] Task due date support

### Medium Term (Q1 2025)
- [ ] Priority/type breakdown statistics (both interfaces)
- [ ] TUI color themes
- [ ] Dashboard mobile improvements
- [ ] Task dependency tracking

### Long Term (Q2+ 2025)
- [ ] Team collaboration features
- [ ] Task assignment and notifications
- [ ] Burndown chart visualization
- [ ] Integration with external tools
- [ ] API rate limiting and caching

---

## 📚 Related Documentation

- **TUI README**: `crates/syntaxis-tui/README.md`
- **Dashboard README**: `crates/syntaxis-dashboard/README.md`
- **API Documentation**: `crates/syntaxis-api/README.md`
- **Architecture Guide**: `ARCHITECTURE.md`

---

**Last Updated**: November 14, 2025
**Status**: Feature Parity Achieved ✅ (Phase 12)
**Tests**: 52 TUI + 12 Dashboard = 64 tests passing ✅