# Project Rules & Principles - syntaxis

## Core Rules

- Follow Rust guidelines from `dev-system/languages/rust/guidelines/`
- PAP = **Project's Architecture Principles** (configuration-driven, zero unsafe, 100% tests)
- **Configuration-driven**, never hardcoded (use TOML + Serde)
- Never patch with hardcoded fallbacks - fix the parsing instead
- Only essential error messages, suppress stack traces except DEBUG

## Project Overview

**syntaxis** is a standalone, production-grade project management platform extracted from the Tools ecosystem:

- **Purpose**: Orchestrate project lifecycle, task definitions, and status tracking
- **Foundation**: VAPORA SST (Software Specification & Tasks) integration
- **Architecture**: Modular monorepo with 6+ operational crates
- **Status**: ✅ Production-ready with 632+ tests passing

## Mandatory Standards

### Code Quality
| Rule | Standard | Status |
|------|----------|--------|
| **Safety** | `#![forbid(unsafe_code)]` - Zero unsafe | ✅ Pass |
| **Errors** | `Result<T>` with `?` operator, no `unwrap()` | ✅ Pass |
| **Documentation** | 100% public API documented (rustdoc) | ✅ Pass |
| **Tests** | 632+ tests, 15+ per module | ✅ Pass |
| **Format** | `cargo fmt --all` required | ✅ Pass |
| **Linting** | `cargo clippy --all-targets` must pass | ✅ Pass |
| **Audit** | `cargo audit` - no vulnerabilities | ✅ Pass |

### Error Handling
Use `thiserror` pattern:
```rust
use thiserror::Error;
#[derive(Error, Debug)]
pub enum WorkspaceError {
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
    #[error("Database error: {0}")]
    Database(String),
}
// Always: fn operation() -> Result<T> { ... }
```

### Module Structure
```rust
mod error;      // Error types (thiserror)
mod types;      // Domain types (Project, Task, Phase)
mod config;     // Configuration (TOML + Serde)
mod managers;   // Business logic (ProjectManager, PhaseManager)
mod persistence;// Database layer (SQLite)
mod tracking;   // Task state tracking (for VAPORA)
#[cfg(test)] mod tests { ... }
```

## Professional Standards

- **Role**: Rust Senior Developer - idiomatic, production-grade code
- **Language**: English only (docs, strings, code)
- **Approach**: TDD (test-driven development)
- **Stack**: NuShell for scripts, Rust for executables
- **Tools**: Justfile for automation, cargo for builds

## Infrastructure

- Use `scripts/` directory for infrastructure
- Declarative & modular via configuration (TOML)
- NuShell for bash-type commands (not Python)
- Rust for executables (not Python)

## Project Tracking

- **NEVER remove `.coder` directory** - contains project lifecycle tracking
- `.coder/` structure: `PHASE_*.md`, `STATUS.md`, `SUMMARY.md`, `COMPLETION.md`
- Tracks migration from syntaxis → syntaxis

## Git & Development

- **NO git commands** unless explicitly requested
- No "ready to commit?" questions - proceed when guidelines met
- Fix bugs completely, don't simplify
- Auto-fix based on guidelines when appropriate

## Architecture Patterns

### Workspace Structure
```
syntaxis/
├── shared/                      # Shared libraries
│   ├── rust-api/               # Shared REST API library (93 tests)
│   ├── rust-tui/               # Shared TUI utilities
│   └── rust/                   # Shared utilities
├── syntaxis/           # Main project
│   ├── crates/                 # 6-8 crates
│   │   ├── syntaxis-core/     # Core library (173 tests)
│   │   ├── syntaxis-cli/      # CLI tool
│   │   ├── syntaxis-tui/      # Terminal UI (10 tests)
│   │   ├── syntaxis-dashboard/# Web Dashboard (52 tests)
│   │   ├── dashboard-client/   # Dashboard client (4 tests)
│   │   ├── dashboard-shared/   # Shared dashboard types (5 tests)
│   │   ├── syntaxis-api/      # REST API (excluded - in progress)
│   │   └── syntaxis-vapora/   # VAPORA adapter (excluded - planned)
│   ├── docs/                   # Documentation
│   ├── scripts/                # Build scripts (NuShell)
│   └── Cargo.toml             # Workspace manifest
├── .coder/                      # Project tracking (NEVER REMOVE)
├── .claude/                     # Claude Code guidelines (local)
├── .project/             # dev-system installation
├── Cargo.toml                  # Root workspace
├── Cargo.lock                  # Dependency lock
├── Justfile                    # Build recipes
└── README.md                   # Project overview
```

### Configuration-Driven Design
- All settings via TOML + Serde
- Zero hardcoded values
- Environment variables for secrets (API keys, DB URLs)
- Feature flags for optional functionality

### Database Layer
```rust
// SQLite with async runtime (tokio)
use sqlx::{sqlite::SqlitePool, Row};

// Connection pooling for performance
let pool = SqlitePool::connect("sqlite:workspace.db").await?;
```

### REST API (axum)
```rust
// Tower middleware stack
use axum::{extract, middleware};
use tower::ServiceBuilder;

let app = ServiceBuilder::new()
    .layer(middleware::TraceLayer::new_for_http())
    .service(routes);
```

### Multi-Interface Architecture
- **CLI** (`workspace`): Command-line tool via clap
- **TUI** (`syntaxis-tui`): Terminal UI via ratatui
- **Dashboard** (`syntaxis-dashboard`): Web UI via Leptos
- **REST API** (`syntaxis-api`): Backend via axum (in progress)

## Important Notes

⚠️ **NEVER**:
- Remove `.coder` directory
- Use `unsafe` code
- Use `unwrap()` in production code
- Hardcode configuration values
- Simplify code when bugs are found

✅ **ALWAYS**:
- Format, lint, test, document
- **Fix bugs completely** - don't simplify code when issues are found
- Use proper error handling with Result<T>
- Document public APIs with rustdoc
- Write tests first (TDD)

## Crate Status

| Crate | Type | Tests | Binaries | Status |
|-------|------|-------|----------|--------|
| syntaxis-core | lib | 173 | - | ✅ Active |
| syntaxis-cli | bin | - | `workspace` | ✅ Active |
| syntaxis-tui | bin | 10 | `syntaxis-tui` | ✅ Active |
| syntaxis-dashboard | lib | 52 | - | ✅ Active |
| syntaxis-api | bin | - | `syntaxis-api` | 🟡 WIP* |
| syntaxis-vapora | lib | - | - | 🟡 Planned* |
| shared-api-lib | lib | 93 | - | ✅ Shared |

*Excluded from workspace members - being developed separately

## VAPORA Integration

syntaxis is designed as the foundation SST (Software Specification & Tasks) for VAPORA:
- Task state tracking with audit trail
- Phase-based project orchestration
- Enterprise-grade change tracking
- Integration hooks for VAPORA orchestration engine

## For Details

- [CODE_STANDARDS.md](./.claude/CODE_STANDARDS.md) - Build, test, verification
- [DEVELOPMENT.md](./.claude/DEVELOPMENT.md) - Workflow, patterns, documentation