syntaxis/.claude/PROJECTS.md

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)

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

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

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

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

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 for complete list

Configuration

Configuration is TOML-based, never hardcoded:

# 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

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 - Project overview
• MIGRATION_STATUS.md - Migration tracking
• PROJECT_RULES.md - Architecture & patterns
• CODE_STANDARDS.md - Quality standards