jesus/syntaxis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init repo

Browse Source
This commit is contained in:
Jesús Pérez 2025-11-15 22:43:00 +00:00
commit d2861a957a
2 changed files with 724 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

510
README.md Normal file
View File

@ -0,0 +1,510 @@
![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

214
imgs/syntax_logo_a.svg Normal file
View File

@ -0,0 +1,214 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 200" width="800" height="200">
<!-- SYNTAXIS Full Logo with Animation -->
<!-- Animated icon on the left, static text on the right -->
<!-- Animated Icon (scaled and positioned) -->
<g transform="translate(20, 20)">
<defs>
<style>
/* Complete cycle: 16s total */
/* 0-4s: Assembly */
/* 4-12s: Ambient breathing (8s) */
/* 12-16s: Disassembly */
@keyframes fullCycle {
/* Assembly phase: 0-25% (0-4s) */
0% {
opacity: 0;
transform: scale(0) rotate(180deg);
}
25% {
opacity: 1;
transform: scale(1) rotate(0deg);
}
/* Ambient phase: 25-75% (4-12s) - stays assembled */
75% {
opacity: 1;
transform: scale(1) rotate(0deg);
}
/* Disassembly phase: 75-100% (12-16s) */
100% {
opacity: 0;
transform: scale(0) rotate(-180deg);
}
}
/* Breathing animation during ambient phase */
@keyframes breatheLoop {
/* No breathing during assembly (0-25%) */
0%, 25% {
transform: scale(1);
opacity: 1;
}
/* Breathing during ambient phase (25-75%) */
37.5% { /* Middle of first breath in ambient */
transform: scale(1.03);
opacity: 0.95;
}
50% { /* Middle of ambient phase */
transform: scale(1);
opacity: 1;
}
62.5% { /* Middle of second breath in ambient */
transform: scale(1.03);
opacity: 0.95;
}
/* No breathing during disassembly (75-100%) */
75%, 100% {
transform: scale(1);
opacity: 1;
}
}
@keyframes breatheLoopMid {
0%, 25% {
transform: scale(1);
opacity: 1;
}
37.5% {
transform: scale(1.04);
opacity: 0.92;
}
50% {
transform: scale(1);
opacity: 1;
}
62.5% {
transform: scale(1.04);
opacity: 0.92;
}
75%, 100% {
transform: scale(1);
opacity: 1;
}
}
@keyframes breatheLoopInner {
0%, 25% {
transform: scale(1);
opacity: 1;
}
37.5% {
transform: scale(1.05);
opacity: 0.9;
}
50% {
transform: scale(1);
opacity: 1;
}
62.5% {
transform: scale(1.05);
opacity: 0.9;
}
75%, 100% {
transform: scale(1);
opacity: 1;
}
}
@keyframes floatLoop {
0%, 25% {
transform: translateY(0);
}
37.5% {
transform: translateY(-3px);
}
50% {
transform: translateY(0);
}
62.5% {
transform: translateY(3px);
}
75%, 100% {
transform: translateY(0);
}
}
/* Apply animations - 16s cycle */
.piece {
animation: fullCycle 16s ease-in-out infinite;
transform-origin: center;
transform-box: fill-box;
}
/* Stagger the pieces */
.a1 { animation-delay: 0s; }
.a2 { animation-delay: 0.3s; }
.a3 { animation-delay: 0.6s; }
.a4 { animation-delay: 0.9s; }
.a5 { animation-delay: 1.2s; }
.a-center { animation-delay: 1.5s; }
/* Breathing layers */
.outer-layer {
animation: breatheLoop 16s ease-in-out infinite;
transform-origin: center;
transform-box: fill-box;
}
.mid-layer {
animation: breatheLoopMid 16s ease-in-out infinite;
transform-origin: center;
transform-box: fill-box;
}
.inner-layer {
animation: breatheLoopInner 16s ease-in-out infinite;
transform-origin: center;
transform-box: fill-box;
}
.center-float {
animation: floatLoop 16s ease-in-out infinite;
transform-origin: center;
transform-box: fill-box;
}
</style>
<linearGradient id="syntaxisGradient" x1="0%" y1="0%" x2="100%" y2="0%">
<stop offset="0%" style="stop-color:#3B7CB8;stop-opacity:1" />
<stop offset="100%" style="stop-color:#D97706;stop-opacity:1" />
</linearGradient>
</defs>
<!-- Outer layer - Top and bottom diamonds -->
<g class="outer-layer">
<path class="piece a1" d="M 100 20 L 110 30 L 100 40 L 90 30 Z" fill="#2C5F8E"/>
<path class="piece a5" d="M 100 140 L 110 150 L 100 160 L 90 150 Z" fill="#2C5F8E"/>
</g>
<!-- Mid layer - Second and fourth rows -->
<g class="mid-layer">
<path class="piece a2" d="M 70 50 L 80 60 L 70 70 L 60 60 Z" fill="#2C5F8E"/>
<rect class="piece a2" x="90" y="50" width="20" height="20" fill="#757773"/>
<path class="piece a2" d="M 130 50 L 140 60 L 130 70 L 120 60 Z" fill="#2C5F8E"/>
<path class="piece a4" d="M 70 110 L 80 120 L 70 130 L 60 120 Z" fill="#2C5F8E"/>
<rect class="piece a4" x="90" y="110" width="20" height="20" fill="#757773"/>
<path class="piece a4" d="M 130 110 L 140 120 L 130 130 L 120 120 Z" fill="#2C5F8E"/>
</g>
<!-- Inner layer - Center row sides -->
<g class="inner-layer">
<path class="piece a3" d="M 40 80 L 50 90 L 40 100 L 30 90 Z" fill="#2C5F8E"/>
<rect class="piece a3" x="60" y="80" width="20" height="20" fill="#757773"/>
<rect class="piece a3" x="120" y="80" width="20" height="20" fill="#757773"/>
<path class="piece a3" d="M 160 80 L 170 90 L 160 100 L 150 90 Z" fill="#2C5F8E"/>
</g>
<!-- Center triangle - floats -->
<g class="center-float">
<path class="piece a-center" d="M 100 80 L 115 105 L 85 105 Z" fill="#D97706"/>
</g>
</g>
<!-- SYNTAXIS Wordmark (Static) -->
<text x="234" y="105" font-family="Inter, -apple-system, system-ui, sans-serif" font-size="48" font-weight="700" fill="url(#syntaxisGradient)" letter-spacing="-1">SYNTAXIS</text>
<!-- Tagline (Static) -->
<text x="234" y="144" font-family="Inter, -apple-system, system-ui, sans-serif" font-size="23" font-weight="400" fill="#6B7280" letter-spacing="0.5">Systematic Orchestration</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 6.5 KiB