# Projects - syntaxis

## Single Project: syntaxis

**syntaxis** is the standalone successor to `syntaxis` in the Tools ecosystem.

### Project Information

| Property | Value |
|----------|-------|
| **Location** | `/Users/Akasha/Development/syntaxis/` |
| **Type** | Rust monorepo |
| **Status** | ✅ Production-ready |
| **Tests** | 632/632 passing |
| **Crates** | 8 (6 active, 2 WIP) |
| **Origin** | Extracted from Tools/syntaxis |
| **Purpose** | Foundation SST (Software Specification & Tasks) for VAPORA |

### Crates Overview

#### Active Crates (6)

| Crate | Path | Type | Tests | Purpose |
|-------|------|------|-------|---------|
| **syntaxis-core** | `core/crates/syntaxis-core/` | lib | 173 | Core project/task/phase management |
| **syntaxis-cli** | `core/crates/syntaxis-cli/` | bin | - | Command-line interface |
| **syntaxis-tui** | `core/crates/syntaxis-tui/` | bin | 10 | Terminal user interface |
| **syntaxis-dashboard** | `core/crates/syntaxis-dashboard/` | lib | 52 | Web dashboard (Leptos) |
| **dashboard-client** | `core/crates/dashboard-client/` | lib | 4 | Dashboard client library |
| **dashboard-shared** | `core/crates/dashboard-shared/` | lib | 5 | Shared dashboard types |

#### Work-in-Progress Crates (2)

| Crate | Path | Type | Status | Purpose |
|-------|------|------|--------|---------|
| **syntaxis-api** | `core/crates/syntaxis-api/` | bin | 🟡 37 errors | REST API server |
| **syntaxis-vapora** | `core/crates/syntaxis-vapora/` | lib | 🟡 Planned | VAPORA orchestration adapter |

#### Shared Libraries (3)

| Library | Path | Tests | Purpose |
|---------|------|-------|---------|
| **shared-api-lib** | `shared/rust-api/shared-api-lib/` | 93 | Unified REST API patterns |
| **shared/rust** | `shared/rust/` | 33 | General utilities (config discovery, etc) |
| **shared/rust-tui** | `shared/rust-tui/` | 262 | TUI widgets and utilities |

### Architecture

```
syntaxis (monorepo root)
├── .coder/                          # Project tracking (NEVER REMOVE)
├── .claude/                         # Development guidelines (local)
├── .project/                  # dev-system installation
├── shared/                          # Shared libraries (3)
│   ├── rust-api/shared-api-lib/    # REST API library (93 tests)
│   ├── rust-tui/                   # TUI utilities (262 tests)
│   └── rust/                        # General utilities (33 tests)
├── syntaxis/               # Main workspace
│   ├── crates/                     # 8 Rust crates
│   │   ├── syntaxis-core/         # Core library (173 tests)
│   │   ├── syntaxis-cli/          # CLI binary
│   │   ├── syntaxis-tui/          # TUI binary (10 tests)
│   │   ├── syntaxis-dashboard/    # Web UI lib (52 tests)
│   │   ├── dashboard-client/       # Dashboard client (4 tests)
│   │   ├── dashboard-shared/       # Shared types (5 tests)
│   │   ├── syntaxis-api/          # API binary (WIP)
│   │   └── syntaxis-vapora/       # VAPORA adapter (WIP)
│   ├── docs/                       # Architecture & guides
│   ├── scripts/                    # Build & deployment scripts
│   └── Cargo.toml                 # Workspace manifest
├── Cargo.toml                      # Root workspace manifest
├── Cargo.lock                      # Dependency lock
├── Justfile                        # Build recipes
├── README.md                       # Project overview
└── MIGRATION_STATUS.md            # Migration tracking
```

### Interfaces

#### 1. Command Line Interface (CLI)
```bash
./target/debug/workspace
./target/debug/workspace project list
./target/debug/workspace task create --name "feature" --project "my-project"
```
- Built with `clap` for argument parsing
- Supports batch operations
- JSON output option for scripting

#### 2. Terminal User Interface (TUI)
```bash
./target/debug/syntaxis-tui
```
- Built with `ratatui` for rich terminal UIs
- Interactive project/task browsing
- Real-time updates via websockets (planned)
- Keyboard-driven navigation

#### 3. Web Dashboard
```bash
# Dashboard hosted by syntaxis-dashboard library
# Accessible at http://localhost:3000
```
- Built with `Leptos` (full-stack Rust/WASM)
- Real-time updates
- Responsive design
- Status: HTML rendering complete

#### 4. REST API (Work-in-Progress)
```bash
# Will run on http://localhost:8080
# JSON-based REST endpoints
# JWT authentication support
```
- Built with `axum` web framework
- Status: 37 type errors in handlers (needs fixing)

### Key Features

✅ **Implemented**
- Project definition and management
- Task creation, assignment, tracking
- Phase-based project orchestration
- Task state transitions with audit trail
- Multiple interface support (CLI, TUI, Dashboard)
- SQLite persistence with async support
- Configuration-driven design

🟡 **In Progress**
- REST API (syntaxis-api)
- VAPORA orchestration adapter (syntaxis-vapora)
- WebSocket real-time updates
- Advanced analytics and reporting

🔮 **Planned**
- PostgreSQL support
- Docker containerization
- Kubernetes deployment
- VAPORA integration complete
- Advanced role-based access control
- Audit trail export

### Database

**Default**: SQLite
- Location: `workspace.db`
- Connection pooling for performance
- Async queries with sqlx
- Compile-time query verification

**Configuration**:
```toml
database_url = "sqlite:workspace.db"
# or environment variable
export DATABASE_URL="sqlite:workspace.db"
```

### Development Status

#### Compilation
- ✅ 6 of 8 crates compile successfully
- 🟡 syntaxis-api: 37 type errors (handler cleanup needed)
- 🟡 syntaxis-vapora: Planning stage

#### Testing
- ✅ 632 tests passing across all crates
- ✅ Code formatting verified
- ✅ Linting passed
- ✅ Security audits clean

#### Build
- ✅ CLI binary: `workspace` (32MB debug, ~10MB release)
- ✅ TUI binary: `syntaxis-tui` (20MB debug, ~6MB release)
- ✅ Dashboard library: Ready for integration
- 🟡 API binary: Not yet built (handler errors)

### Dependencies

**Core Dependencies**:
- `tokio` (1.x) - Async runtime
- `axum` (0.8) - Web framework
- `sqlx` (0.8) - Database client
- `serde` (1.0) - Serialization
- `thiserror` (2.0) - Error handling
- `leptos` (0.8.12) - Web framework

**See [DEPENDENCIES.md](./.claude/DEPENDENCIES.md) for complete list**

### Configuration

Configuration is TOML-based, never hardcoded:

```toml
# syntaxis.toml
[workspace]
project_root = "."
database_url = "sqlite:workspace.db"

[ui]
theme = "dark"
log_level = "info"
```

### Integration with VAPORA

syntaxis is designed as the foundation SST for VAPORA:

- **Task State Tracking**: Provides TaskStatus and TaskStateChange tracking
- **Phase Orchestration**: Phase-based project management with validation
- **Event System**: Ready for VAPORA event hooks
- **Metadata Support**: Flexible metadata for VAPORA extensions

### Migration Notes

syntaxis was extracted from syntaxis to:
1. Decouple project management from Tools ecosystem
2. Create standalone VAPORA integration point
3. Enable independent development and versioning
4. Maintain shared libraries through path dependencies

Original syntaxis remains in Tools for reference but syntaxis is the active implementation.

### Quick Start

```bash
cd /Users/Akasha/Development/syntaxis

# Build all
cargo build --release

# Run tests
cargo test --workspace

# Run CLI
./target/debug/workspace --help

# Run TUI
./target/debug/syntaxis-tui

# Code quality checks
just check-all
```

### For Details

See:
- [README.md](../../README.md) - Project overview
- [MIGRATION_STATUS.md](../../MIGRATION_STATUS.md) - Migration tracking
- [PROJECT_RULES.md](./.claude/PROJECT_RULES.md) - Architecture & patterns
- [CODE_STANDARDS.md](./.claude/CODE_STANDARDS.md) - Quality standards
