jesus/syntaxis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
syntaxis/README.md
Jesús Pérez d2861a957a init repo
2025-11-15 22:43:00 +00:00

16 KiB
Raw Blame History

SYNTAXIS Logo

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:

# 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

# 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:

🎯 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.

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.

// 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:

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 and BOOTSTRAP_DIAGRAMS.md.

Installation Options

# 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:

source ~/.bashrc  # or ~/.zshrc, ~/.config/fish/config.fish

Then verify installation:

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

cd /Users/Akasha/Development/syntaxis
cargo build --workspace

Test

cargo test --workspace

Run API Server

cargo run -p syntaxis-api
# Server runs on http://localhost:3001

Run Terminal UI

cargo run -p syntaxis-tui

Run Web Dashboard

cargo run -p syntaxis-dashboard
# Dashboard on http://localhost:3000

Run CLI

cargo run -p syntaxis-cli -- --help

📋 Commands

All available via just:

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

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

// 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

Project Documentation

✅ 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

Development

🔗 Links

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