syntaxis/docs/core/quick-reference.md

# Quick Reference: Dashboard & TUI Components

## Overview at a Glance

```
API Server (Port 3000)
    ↓
  ┌─────────────┬──────────────┐
  ↓             ↓              ↓
Dashboard    TUI App        CLI
(Port 3001) (Terminal)   (stdout)
```

---

## 1. API Server (syntaxis-api)

**Port**: 3000  
**Config**: `syntaxis-api-config.template.toml` → `syntaxis-api-config.toml`  
**Database**: SQLite (`/tmp/syntaxis-data.db`)

```bash
cargo run -p syntaxis-api --config syntaxis-api-config.toml
```

**Key Endpoints**:
- GET `/api/projects` - List all projects
- GET `/api/projects/{id}` - Get project details
- GET `/api/projects/{id}/status` - Project status
- GET `/api/projects/{id}/checklists` - Checklist items
- POST `/api/projects` - Create project

---

## 2. Web Dashboard (syntaxis-dashboard)

**Port**: 3001  
**Framework**: Leptos (Rust) + Axum  
**Config**: Hardcoded (development phase)  
**Status**: Placeholder HTML with Tailwind CSS

```bash
cargo run -p syntaxis-dashboard
# Open http://localhost:3001
```

**Key Files**:
- Entry: `/crates/syntaxis-dashboard/src/bin/main.rs`
- API Client: `/crates/syntaxis-dashboard/src/api.rs`
- Components: `/crates/syntaxis-dashboard/src/components/`
  - `header.rs`, `button.rs`, `card.rs`, `progress.rs`

**Communicates with API at**: `http://localhost:3000/api`

---

## 3. Terminal UI (syntaxis-tui)

**Framework**: Ratatui 0.25 + Crossterm  
**Config**: Hardcoded (development phase)  
**Key Bindings**: Arrow keys/hjkl (nav), Enter (select), 'c' (create), 's' (security), Esc (back), 'q' (quit)

```bash
cargo run -p syntaxis-tui
```

**Key Files**:
- Entry: `/crates/syntaxis-tui/src/main.rs`
- App State: `/crates/syntaxis-tui/src/app.rs` (R-STATE-SEPARATION pattern)
- UI Rendering: `/crates/syntaxis-tui/src/ui.rs` (R-WIDGET-COMPOSITION pattern)
- API Client: `/crates/syntaxis-tui/src/api.rs`
- Theme: `/crates/syntaxis-tui/src/theme.rs` (5 themes available)
- Screens: `/crates/syntaxis-tui/src/screens/`
  - `projects.rs`, `phases.rs`, `checklist.rs`

**Screens**:
1. **ProjectsList** - Default view, shows all projects
2. **ProjectDetail** - Details for selected project
3. **Security** - Security assessment
4. **CreateProject** - New project form

**Communicates with API at**: `http://localhost:3000/api`

---

## 4. Shared TUI Library (rust-tui)

**Location**: `/crates/rust-tui/`  
**Purpose**: Reusable Ratatui components and patterns

**Key Exports**:
- `Theme` - Color/style management (5 variants)
- `AppHeader`, `AppFooter` - Widgets
- `DirtyFlag` - Pattern implementation
- `Plugin`, `PluginRegistry` - Plugin system

**Design Patterns Implemented**:
- **R-STATE-SEPARATION** - State ↔ Rendering separation
- **R-WIDGET-COMPOSITION** - Pure rendering functions
- **R-EVENT-LOOP** - Non-blocking event polling
- **R-RESPONSIVE-LAYOUT** - Terminal layout responsive
- **R-CONSISTENT-THEMING** - Unified theme system

---

## 5. Configuration Files

| File | Location | Purpose |
|------|----------|---------|
| `syntaxis-api-config.template.toml` | Root | API config template |
| `syntaxis-api-config.toml` | Root | Actual API config (after copy) |
| `configs/features/*.toml` | Root/configs/features | Feature configs |
| `Cargo.toml` (workspace) | Root | Workspace definition |

**API Config Features** (enable/disable in main config):
- `database` - Connection pooling, migrations
- `health` - Status endpoint, health checks
- `metrics` - Prometheus metrics
- `rate_limit` - Request throttling
- `auth` - API key validation
- `cache` - In-memory caching
- `multi_tenant` - Tenant isolation

---

## 6. Key Design Patterns

### R-STATE-SEPARATION
```rust
pub struct App {
    pub screen: Screen,              // UI state
    pub dirty: bool,                 // Needs redraw?
    pub projects: Vec<ProjectDto>,   // Data
    pub api: ApiClient,              // Dependencies
}

// Mutations go through methods, not direct assignment
app.nav_down();      // ✅ Correct
app.screen = X;      // ❌ Wrong (not idiomatic)
```

### R-WIDGET-COMPOSITION
```rust
// Pure rendering - reads state, never modifies
fn render(f: &mut Frame<'_>, app: &App) {  // &App, not &mut App
    // Rendering logic here
}
```

### R-EVENT-LOOP
```rust
loop {
    // Only redraw when dirty
    if app.dirty {
        terminal.draw(|f| render(f, &app))?;
        app.mark_rendered();
    }
    
    // Handle events (non-blocking with 250ms timeout)
    match events.next()? {
        // Event handling
    }
}
```

---

## 7. Startup Sequence

**Step 1**: Start API server (must be first)
```bash
cargo run -p syntaxis-api --config syntaxis-api-config.toml
# Listening on http://127.0.0.1:3000
```

**Step 2**: Start TUI (optional)
```bash
cargo run -p syntaxis-tui
# Connects to API at http://localhost:3000/api
```

**Step 3**: Start Dashboard (optional, in separate terminal)
```bash
cargo run -p syntaxis-dashboard
# Serves at http://127.0.0.1:3001
# Connects to API at http://localhost:3000/api
```

---

## 8. Testing & Benchmarks

**Run all tests**:
```bash
cargo test --workspace
```

**Run TUI tests**:
```bash
cargo test -p syntaxis-tui
```

**Run TUI benchmarks** (Criterion):
```bash
cargo bench -p syntaxis-tui
# Tests: rendering_performance, event_handling, state_mutations
```

---

## 9. Important Details

### Zero Unsafe Code Policy
- All crates have `#![forbid(unsafe_code)]`
- Uses safe Rust patterns exclusively
- No unwrap() in production code

### API Integration
- **Dashboard**: `reqwest` HTTP client → `http://localhost:3000/api`
- **TUI**: `reqwest` HTTP client → `http://localhost:3000/api`
- **Both**: Same endpoint structure, same DTOs

### Theme System
**TUI Themes**:
- `default()` - Cyan (recommended)
- `dark()` - Dark mode
- `light()` - Light mode
- `minimal()` - High contrast
- `professional()` - Corporate blue

**Builder pattern**:
```rust
let theme = AppTheme::default()
    .with_bold_headers()
    .with_italic_metadata();
```

### Event Handling
**TUI Key Bindings**:
- `↑/k` - Up
- `↓/j` - Down
- `Enter` - Select
- `'c'` - Create project
- `'s'` - View security
- `'b'/Esc` - Back
- `'q'/Ctrl+C` - Quit

---

## 10. File Structure Summary

```
syntaxis/
├── syntaxis-api-config.template.toml  # API config template
├── PROJECT_EXPLORATION.md              # Detailed analysis (this doc)
├── QUICK_REFERENCE.md                  # Quick reference (this file)
└── crates/
    ├── syntaxis-core/                 # Business logic
    ├── syntaxis-api/                  # REST API server (Port 3000)
    ├── syntaxis-dashboard/            # Web UI (Port 3001)
    │   ├── src/bin/main.rs
    │   ├── src/api.rs                  # API client
    │   ├── src/components/             # Leptos components
    │   └── src/types.rs
    ├── syntaxis-tui/                  # Terminal UI
    │   ├── src/main.rs
    │   ├── src/app.rs                  # State management
    │   ├── src/ui.rs                   # Rendering
    │   ├── src/api.rs                  # API client
    │   ├── src/theme.rs                # Theme system
    │   ├── src/screens/                # UI screens
    │   └── benches/                    # Performance tests
    ├── rust-tui/                       # Shared TUI library
    │   └── src/
    │       ├── theme.rs                # Theme system
    │       ├── widgets.rs              # Reusable widgets
    │       ├── patterns.rs             # R-* patterns
    │       └── plugin.rs               # Plugin system
    ├── syntaxis-cli/                  # CLI interface
    └── vapora-project-lifecycle/               # VAPORA integration
```

---

## 11. Common Tasks

### Build everything
```bash
cargo build --workspace --release
```

### Run all tests
```bash
cargo test --workspace
```

### Check code quality
```bash
cargo fmt --check
cargo clippy --all-targets --all-features
```

### Generate documentation
```bash
cargo doc --no-deps --open
```

### Run with debug logging
```bash
RUST_LOG=debug cargo run -p syntaxis-tui
```

---

## Quick Troubleshooting

**API server won't start**
- Check port 3000 is free: `lsof -i :3000`
- Check config file exists: `syntaxis-api-config.toml`
- Ensure database directory exists: `mkdir -p /tmp`

**Dashboard can't connect to API**
- Is API server running on port 3000?
- Check CORS is enabled in config: `cors_enabled = true`
- API base URL is hardcoded: `http://localhost:3000/api`

**TUI won't connect to API**
- Is API server running on port 3000?
- API base URL is hardcoded: `http://localhost:3000/api`
- Check terminal size is at least 80x24 characters

**Tests failing**
- Run: `cargo clean && cargo test --workspace`
- Check database isn't locked (SQLite)
- Run single test: `cargo test -p syntaxis-tui test_name`