251 lines
7.7 KiB
Markdown
251 lines
7.7 KiB
Markdown
|
# 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
|