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)

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

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)

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

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

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

R-EVENT-LOOP

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)

cargo run -p syntaxis-api --config syntaxis-api-config.toml
# Listening on http://127.0.0.1:3000

Step 2: Start TUI (optional)

cargo run -p syntaxis-tui
# Connects to API at http://localhost:3000/api

Step 3: Start Dashboard (optional, in separate terminal)

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:

cargo test --workspace

Run TUI tests:

cargo test -p syntaxis-tui

Run TUI benchmarks (Criterion):

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:

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

cargo build --workspace --release

Run all tests

cargo test --workspace

Check code quality

cargo fmt --check
cargo clippy --all-targets --all-features

Generate documentation

cargo doc --no-deps --open

Run with debug logging

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