syntaxis/README.md

![SYNTAXIS Logo](imgs/syntax_logo_a.svg)

# SYNTAXIS

> **Systematic Orchestration, Perfectly Arranged**

**SYNTAXIS** is a production-grade project orchestration platform that brings systematic arrangement to modern software workflows. Like its namesake from ancient Greek (σύνταξις - arrangement, composition), SYNTAXIS transforms chaotic project management into perfectly ordered processes.

**Core Philosophy**: *Every task has its perfect place in the syntax of your workflow.*

## 🎯 What Is SYNTAXIS?

SYNTAXIS is designed for developers and teams who demand:

- **Systematic Orchestration**: Structured projects with clear phases and transitions
- **Production-Grade Quality**: 691+ tests, zero unsafe code, 100% documented
- **Multiple Interfaces**: Choose your workflow—CLI, TUI, Dashboard, or REST API
- **Scalable Persistence**: From local SQLite to distributed SurrealDB
- **VAPORA Ready**: Official SST foundation for AI agent orchestration
- **Zero Compromises**: Rust-built, fully tested, production-ready from day one

Perfect for individual developers managing side projects, development teams scaling workflows, and enterprises orchestrating mission-critical systems.

---

## ⚡ Quick Start

Get started with SYNTAXIS in 30 seconds:

```bash
# Install via Cargo
cargo install syntaxis

# Initialize a new project
syntaxis init my-project

# Start orchestrating
syntaxis orchestrate
```

**Choose your interface based on your workflow:**

- **CLI** (`syntaxis`) — Perfect for automation, CI/CD, scripting
- **TUI** (`syntaxis tui`) — Vim-style navigation, keyboard-driven focus
- **Dashboard** (`syntaxis-dashboard`) — Web-based team visibility
- **REST API** (`syntaxis-api`) — Integration and custom workflows

---

## 🏆 Key Strengths

### Production-Grade Quality
✅ **691+ Automated Tests** — Every feature tested, every edge case covered
✅ **Zero Unsafe Code** — `#![forbid(unsafe_code)]` enforced
✅ **100% Documented** — All public APIs documented with rustdoc
✅ **Zero Technical Debt** — No shortcuts, no compromises

### Scalable Architecture
- **Start Simple**: SQLite (local, zero config)
- **Scale Seamlessly**: SurrealDB (team-ready, distributed)
- **Deploy Anywhere**: Docker, Kubernetes, cloud-native ready

### Feature-Rich Yet Simple
- **Systematic Phases**: Create → Develop → Publish → Archive
- **Task Management**: Priority, type, state tracking with audit trails
- **Real-Time Updates**: WebSocket support across all interfaces
- **Configuration-Driven**: All settings via TOML, no hardcoding

---

## 📦 Components

### syntaxis-core (10K+ lines)
Core business logic for:
- **Projects**: Create, manage, and organize projects
- **Phases**: Project lifecycle phases (create → devel → publish → archive)
- **Tasks**: Work items with priority, type, and state tracking
- **Tracking**: Full state change history and audit trail
- **Templates**: Auto-generate project structures
- **Checklists**: Phase-based progress validation

### syntaxis-api (3.3K+ lines)
REST API server with:
- RESTful endpoints for all operations
- WebSocket support for real-time updates
- Authentication & authorization
- Rate limiting & metrics
- TLS support
- JSON request/response

### syntaxis-tui (5.3K+ lines)
Terminal User Interface:
- Ratatui-based interactive UI
- Vim-style keyboard navigation (hjkl)
- Real-time task management
- Multi-screen navigation
- SSH-friendly (works over remote connections)

### syntaxis-dashboard (1.4K+ lines)
Web Dashboard:
- Modern responsive design
- Mouse & keyboard support
- Advanced filtering & analytics
- Mobile-friendly layout
- Leptos-based (WASM)

### syntaxis-cli
Command-line tool:
- `syntaxis` binary for scripting and automation
- Full CLI coverage with structured subcommands
- Integration with shell workflows and CI/CD pipelines

### syntaxis-vapora
VAPORA adapter:
- Integrates syntaxis-core into VAPORA SST
- Handles orchestration coordination
- Agent integration hooks

## 💾 Database Support

syntaxis supports **both SurrealDB 2.3 and SQLite** via configuration:

### SurrealDB 2.3 (Modern, Multi-Backend)
- ✅ Embedded in-memory mode (development, testing)
- ✅ Embedded file-based mode (RocksDB persistence)
- ✅ Server mode (integration testing, multiple clients)
- ✅ Docker deployment (reproducible setup)
- ✅ Kubernetes deployment (enterprise production)
- **Quick Setup**: `cp configs/database-surrealdb.toml configs/database.toml && surreal start --bind 127.0.0.1:8000 memory`

### SQLite (Default, Recommended)
- ✅ Default configuration (no setup needed)
- ✅ Local file-based persistence
- ✅ Async pooled connections
- ✅ Zero external dependencies
- **Quick Setup**: `cargo run -p syntaxis-cli` (uses SQLite by default)

### Switching Databases
```bash
# Use SurrealDB
cp configs/database-surrealdb.toml configs/database.toml

# Use SQLite (default)
cp configs/database-default.toml configs/database.toml
```

**For detailed setup instructions:**
- SurrealDB: See [SURREALDB_QUICK_START.md](./SURREALDB_QUICK_START.md)
- SurrealDB Production: See [SURREALDB_SETUP_GUIDE.md](./SURREALDB_SETUP_GUIDE.md)
- SurrealDB Configuration: See [configs/database-surrealdb.toml](./configs/database-surrealdb.toml)

---

## 🎯 Who Uses SYNTAXIS?

### Individual Developers
**Your Personal Workflow Composer**

SYNTAXIS brings systematic order to your projects. No more scattered TODOs, forgotten tasks, or chaotic sprints. Every task has its place in the syntax of your workflow.

```bash
syntaxis init my-project
syntaxis tui  # Beautiful terminal UI
```

### Development Teams
**Team Orchestration, Systematically Arranged**

Stop fighting with Jira. Stop settling for Trello. SYNTAXIS provides just enough structure for clarity, with just enough flexibility for creativity.

- Shared projects with real-time collaboration
- Phase-based workflow management
- Complete audit trails for accountability

### Enterprises
**Enterprise Orchestration Without Enterprise Complexity**

Production-grade doesn't mean complicated. SYNTAXIS scales to thousands of tasks without losing the systematic simplicity at its core.

- SurrealDB + Kubernetes = Infinite scale
- Comprehensive security and audit features
- Multi-team support and RBAC

### VAPORA Ecosystem
**The Systematic Foundation for AI Orchestration**

SYNTAXIS provides the structured task layer that VAPORA agents need to orchestrate intelligently. Task states trigger agents. Agents update tasks. The cycle continues, systematically.

```rust
// VAPORA agents can now orchestrate via SYNTAXIS
agent.on_task_state_change(|task| {
    // Perform intelligent actions based on task state
}).await;
```

---

## 🚀 Installation

### One-Command Installation (Recommended)

Install everything with a single command - the installer handles all dependencies:

```bash
curl -sSL https://raw.githubusercontent.com/core/syntaxis/main/install.sh | bash
```

This installs:
- ✅ Rust toolchain via rustup bootstrap (if needed)
- ✅ NuShell via Rust compilation (if needed)
- ✅ Just task runner via Rust compilation (if needed)
- ✅ All binaries: `syntaxis`, `syntaxis-tui`, `syntaxis-dashboard`, `syntaxis-api`
- ✅ Configuration files to `~/.config/syntaxis/`
- ✅ Environment setup

**Installation takes 15-30 minutes** (mostly cargo build time on first install).

#### How It Works: Bootstrap Compiler

The installer uses Rust's **bootstrap compiler architecture** to avoid circular dependencies:

1. **Download pre-compiled Rust** (100MB) via `curl https://sh.rustup.rs | bash`
   - Works on any system (no compilation needed for bootstrap)
2. **Use Rust to compile everything else** (NuShell, Just, workspace binaries)
   - Once Rust exists, we can compile any Rust source code
3. **Deploy & configure** all components automatically

**Why this works:** Only the first compiler (Rust) is pre-compiled. Everything else is built from source using that compiler. No circular dependency!

**For detailed explanation:** See [BOOTSTRAP_EXPLAINED.md](./BOOTSTRAP_EXPLAINED.md) and [BOOTSTRAP_DIAGRAMS.md](./BOOTSTRAP_DIAGRAMS.md).

#### Installation Options

```bash
# Unattended mode (no prompts)
bash install.sh --unattended

# Install to custom directory
bash install.sh --prefix /opt/workspace

# Only deploy configs (binaries already installed)
bash install.sh --config-only

# See what would be installed without making changes
bash install.sh --dry-run

# Full help
bash install.sh --help
```

After installation, reload your shell:
```bash
source ~/.bashrc  # or ~/.zshrc, ~/.config/fish/config.fish
```

Then verify installation:
```bash
syntaxis --help
syntaxis-tui --version
which syntaxis-dashboard
```

### Manual Installation (Developers)

For development or advanced installation:

#### Prerequisites
- Rust 1.75+
- Cargo
- NuShell (for scripts)

#### Build
```bash
cd /Users/Akasha/Development/syntaxis
cargo build --workspace
```

#### Test
```bash
cargo test --workspace
```

#### Run API Server
```bash
cargo run -p syntaxis-api
# Server runs on http://localhost:3001
```

#### Run Terminal UI
```bash
cargo run -p syntaxis-tui
```

#### Run Web Dashboard
```bash
cargo run -p syntaxis-dashboard
# Dashboard on http://localhost:3000
```

#### Run CLI
```bash
cargo run -p syntaxis-cli -- --help
```

## 📋 Commands

All available via `just`:

```bash
just check              # cargo check
just test              # cargo test
just fmt               # cargo fmt
just lint              # cargo clippy
just check-all         # Full verification
just audit             # Security audit
just doc               # Generate docs

just run-api           # Start API server
just run-tui           # Start TUI
just run-dashboard     # Start web dashboard
just run-cli --help    # Run CLI
```

## 🏗️ Architecture

```
syntaxis/ (MONOREPO ROOT)
│
├── shared/             (Reusable libraries)
│   ├── rust-api/
│   ├── rust-tui/
│   └── rust/           (Config, utilities)
│
├── syntaxis/  (Main project)
│   ├── crates/
│   │   ├── syntaxis-core/    (Core library)
│   │   ├── syntaxis-api/     (REST server)
│   │   ├── syntaxis-tui/     (Terminal UI)
│   │   ├── syntaxis-dashboard/ (Web dashboard)
│   │   ├── syntaxis-cli/     (CLI tool)
│   │   └── syntaxis-vapora/  (VAPORA adapter)
│   │
│   ├── docs/
│   ├── templates/
│   ├── scripts/
│   └── README.md
│
├── .coder/            (Project tracking)
├── .claude/           (Guidelines & rules)
├── Cargo.toml         (Workspace root)
├── Justfile           (Build recipes)
└── README.md          (This file)
```

## 🔌 VAPORA Integration

syntaxis is designed as the **foundation for VAPORA SST**.

### How VAPORA Uses It

1. **Project Management**: Defines projects, phases, tasks
2. **Task State**: Tracks task progress and state changes
3. **Orchestration**: VAPORA orchestrator triggers agents based on pending tasks
4. **Automation**: Agents update task states → VAPORA reacts

### Setup in VAPORA

```toml
# vapora/vapora-sst/Cargo.toml
[dependencies]
syntaxis-core = { path = "../../Development/core/core/crates/syntaxis-core" }
```

```rust
// vapora/vapora-sst/src/orchestrator.rs
use workspace_core::*;

impl VaporaOrchestrator {
    async fn process_pending_tasks(&self, project_id: &str) -> Result<()> {
        let tasks = self.workspace_api.get_pending_tasks(project_id).await?;

        for task in tasks {
            // Trigger agents, update state, etc.
        }

        Ok(())
    }
}
```

## 📚 Documentation

### Installation & Bootstrap
- **[BOOTSTRAP_EXPLAINED.md](./BOOTSTRAP_EXPLAINED.md)** - Complete explanation of how Rust bootstrap compiler works, why we use it, and how it enables one-command installation
- **[BOOTSTRAP_DIAGRAMS.md](./BOOTSTRAP_DIAGRAMS.md)** - Visual diagrams and flowcharts explaining the bootstrap process
- **[INSTALLATION_GUIDE.md](./INSTALLATION_GUIDE.md)** - Step-by-step installation and post-install setup
- **[CONFIGURATION_GUIDE.md](./CONFIGURATION_GUIDE.md)** - Configuration options and customization

### Project Documentation
- **[Architecture](./core/docs/ARCHITECTURE.md)** - System design
- **[API Reference](./core/docs/API.md)** - REST endpoints
- **[CLI Guide](./core/docs/CLI.md)** - Command-line usage
- **[VAPORA Integration](./core/docs/VAPORA_INTEGRATION.md)** - VAPORA setup
- **[Quick Start](./core/docs/QUICK_START.md)** - Getting started

## ✅ Code Quality

- ✅ **No unsafe code** - `#![forbid(unsafe_code)]`
- ✅ **No unwrap()** - Proper error handling with `Result<T>`
- ✅ **100% documented** - All public APIs documented with rustdoc
- ✅ **100+ tests** - Comprehensive test coverage
- ✅ **Idiomatic Rust** - Following language best practices
- ✅ **Formatted & linted** - `cargo fmt` & `cargo clippy` compliant

---

## 💡 Why SYNTAXIS?

### vs. Jira
Jira is complex, expensive, and overwhelming. SYNTAXIS is systematic, affordable, and clarity-focused. Perfect for 90% of teams who don't need enterprise complexity.

### vs. GitHub Projects
GitHub Projects is basic and locked into GitHub. SYNTAXIS is rich, standalone, and fully orchestration-capable. For serious project management.

### vs. Linear
Linear is beautiful but proprietary and SaaS-only. SYNTAXIS is open source with self-hosting options and true multi-interface flexibility.

### vs. Asana/Monday.com
These tools are generic and business-focused. SYNTAXIS is developer-first, technically excellent, and systematically designed.

### Unique Advantages
1. **Multi-Interface Excellence**: CLI + TUI + Dashboard + REST API
2. **Production-Grade Quality**: 691+ tests, zero unsafe code, 100% documented
3. **Systematic Philosophy**: Based on arrangement/composition principles
4. **Database Flexibility**: Switch SQLite ↔ SurrealDB via config change
5. **VAPORA Ready**: Official AI orchestration foundation
6. **No Vendor Lock-in**: Open source, self-hosted, your data

---

## 🎯 Project Status

- ✅ **Phase 1-12**: Core functionality complete (691+ tests)
- ✅ **Fully Renamed**: All references updated to syntaxis
- ✅ **Multi-Interface**: CLI, TUI, Dashboard, and REST API operational
- ✅ **Production-Ready**: Beta status, ready for real-world use
- 🔜 **Coming Soon**: VAPORA integration enhancements, advanced features

## 📝 Guidelines

All code follows the guidelines in `.claude/`:

- **PROJECT_RULES.md** - Architecture & design principles
- **CODE_STANDARDS.md** - Build, test, verification
- **DEVELOPMENT.md** - Workflow & patterns
- **projec_best_practices.md** - Configuration-driven design

When syntaxis rules are finalized, custom `.claude/SYNTAXIS.md` will be added.

## 🤝 Contributing

All contributions must:

- ✅ Pass `cargo check --workspace`
- ✅ Pass `cargo test --workspace`
- ✅ Pass `cargo clippy --all-targets`
- ✅ Pass `cargo fmt --all`
- ✅ Include tests for new features
- ✅ Include documentation

## 📄 License

MIT OR Apache-2.0

## 📖 Learn More

### Documentation
- [Architecture Guide](./core/docs/ARCHITECTURE.md) — System design and patterns
- [API Reference](./core/docs/API.md) — REST endpoint documentation
- [CLI Guide](./core/docs/CLI.md) — Command-line usage
- [VAPORA Integration](./core/docs/VAPORA_INTEGRATION.md) — AI orchestration setup

### Development
- [Building from Source](./core/HOWTO-BUILD.md) — Compilation and releases
- [Configuration Guide](./core/HOWTO-CONFIG.md) — TOML setup and customization
- [Contributing Guidelines](./CONTRIBUTING.md) — How to contribute

---

## 🔗 Links

- **Website**: https://syntaxis.dev
- **GitHub**: https://github.com/syntaxis
- **Documentation**: [Complete Guide](./core/docs/ARCHITECTURE.md)
- **Root directory**: `/Users/Akasha/Development/syntaxis`
- **Brand Identity**: [SYNTAXIS Brand Guide](./difusion/SYNTAXIS_BRAND_IDENTITY.md)

---

**Status**: Production Ready (Beta) ✅
**Last Updated**: 2025-11-15
**Framework Version**: 0.1.0
**Test Coverage**: 691+ tests (all passing) ✅
**Code Quality**: Zero unsafe code, 100% documented, zero warnings ✅

---

**SYNTAXIS** — Where systematic meets orchestration.
Built in Rust. Tested rigorously. Designed for clarity. Ready for production.
 e